Repository navigation
feat(steward): add scoped PR signal monitors and chat_root report delivery - #9182
Conversation
…ivery Signed-off-by: LoopX Agent <[email protected]>
loopx-agent
left a comment
There was a problem hiding this comment.
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
Reviewer: model_agent · Gemini · Google DeepMind · self_reported
动机 / Motivation
当受托 Steward 需要并行运行多个 PR 信号监控任务时,既有共享信号指纹门控会导致跨监控串扰与散装待办轰炸。
- 受影响调用方:受托 Steward 运维调用方与多 Monitor 管理路径(monitor.create/monitor.update、StewardTurnHost 及 LarkStewardReports)。
- 改进前后对比:修改前:所有 PR Monitor 共享同一包含全量 PR 与 portfolio/inbox 的结果哈希,无法按关注范围独立唤醒,PR 跨越 24 小时停滞阈值不会触发哈希变化,且异常逐条写入散装 user_action 待办或污染每日总报;修改后:每个 Monitor 按独立的 steward_signal_monitor_scope_v0 过滤仓库列表与信号源、于达标跃迁 >=24h 时单次翻转哈希,并在提交后将单篇聚合 Markdown 汇报原子入队并直达 App 与飞书私聊根会话(chat_root)。
- 可观测交付结果:启用 signal_scope 的 Monitor 各自产出隔离的 result_hash 与 scoped_repository_items,支持领域中立的 required_approver_declarations 与 DISMISSED 重放;输出 steward_owner_report 时创建 0 条 user 待办并在飞书 chat_root 完成幂等投递。
- 非目标边界:本 PR 不修改每日 09:00 全局 periodic_report 的既有调度/预设生成权限,也不赋予 Steward 自动合并 PR 或免评审旁路权限。
改动思路 / Approach
整体严格沿 TypeScript 控制面唯一策略所有权演进并保持默认关闭向后兼容:
- 在
steward_managed_mode.ts定义steward_signal_monitor_scope_v0与normalizeStewardSignalMonitorScope,支持领域中立的required_approver_declarations(重放exact_head_reviews并正确剥离DISMISSED状态)、author_mode/authors与min_stalled_hours阈值跃迁,未配置signal_scope时与基线逐字段同构。 - 在
steward_monitor.py与monitor.create/monitor.update(chat_action_normalization.py、chat_actions.py、chat/monitor_actions.py)持久化scopes/<target_key>.json并仅拉取所需维度、写入scoped_repository_items。 - 在
steward_turn.py新增可选steward_owner_report验证与steward_monitor_report_delivery_v0队列落盘;在LarkStewardReports._reconcile_monitor_reports独立于每日周期日报订阅开关,复用原受众_deliver(..., reply_placement="chat_root", finalize_source=False)实现单次幂等直达。
架构评估与边界:复用既有 monitor_todo 调度、TS 控制面信号归属权与 Lark _deliver/_original_route,不引入并行守护进程或第二套决策状态,未开启新字段时与主干基线完全一致。 当前边界:当前 PR 边界覆盖 TS 控制面作用域过滤、monitor 动作持久化、Turn 聚合汇报入队与飞书 chat_root 幂等送达;线上 4-Monitor 配置切换与历史待办清理由发布后的运维切换步骤执行。
具体改动 / Changes
- 规格依据(spec_basis):对照仓库 TypeScript 控制面演进契约与既有 Lark 私聊出站投递边界(无单独书面 RFC 规格文件,
spec_source=none),本次改动5464acfc24e15eea3da7dc103f00b7c125c4512a已完整落地作用域隔离哈希、min_stalled_hours跃迁与单篇聚合直达投递。
关键代码讲解
normalizeStewardSignalMonitorScope(loopx/control_plane/collaboration/steward_managed_mode.ts:860):严格校验schema_version、布尔开关与pr_filter字段白名单,去重小写排序规范化required_approver_declarations与authors,拒绝未知字段与非正min_stalled_hours。observeStewardSignalMonitor(loopx/control_plane/collaboration/steward_managed_mode.ts:1027):signal_scope == null时执行完全相同的旧哈希逻辑并省略scoped_repository_items;启用作用域时仅纳入启用维度与过滤后 PR,重放exact_head_reviews过滤已撤销结论,并在跨过min_stalled_hours时仅随stalled_threshold_met: true跃迁翻转一次而不受采集时钟影响。StewardTurnHost._normalize_steward_actions(loopx/capabilities/native_chat/steward_turn.py:1131)与落盘分支(steward_turn.py:1605):校验可选steward_owner_report(1..24000字符或{markdown}),提交后原子写入deliveries/<turn_id>.json并直接返回聚合 Markdown。LarkStewardReports._reconcile_monitor_reports(loopx/extensions/lark/steward_reports.py:105):在reconcile()中先于周期报告订阅判断运行,锁定单个投递文件并验证native_loopx提交事件、self.reports.selected(binding_id)实时授权与不可变original_route后,以chat_root与finalize_source=False发送一次并凭回执去重。
对主干的风险 / Risks
- 默认关闭隔离与兼容(default_off_isolation / observable_semantics):未配置
signal_scope时observeStewardSignalMonitor输出完全不变;未返回steward_owner_report时现有 Monitor 照常生成steward_user_actions或context_handoff。已由observeStewardSignalMonitornull/undefined对照测试与既有 TS/Python 套件验证通过。 - 并发、越权与伪阳性风险(authority_semantics / failure_analysis):
_reconcile_monitor_reports强制核对 Turn 身份、实时 binding 启用状态及原 P2P 受众;finalize_reactionsSkip Set 纳入steward_monitor_report避免错误终结原消息表情;required_approver_declarations使用结构化reviewer_declaration+DISMISSED状态重放,消除硬编码厂商正则与已撤销审批误判。 - 本地验证实况:
node --experimental-strip-types --test tests/control_plane_ts/steward_managed_mode.test.tsPASS(16/16)、pytest -n 4PASS(173/173,注:55 并发-n auto曾因 CPU 争抢触发 15s TS IPC 超时,降为-n 4后稳定全过)、架构/创建回归测试 PASS(112/112[100%])、ruff checkPASS、examples/semantic-vocabulary-drift-smoke.py --git-diff origin/mainPASS、loopx check12 文件 PASS、canary premerge --tier quickPASS(3/3,0 阻塞)。
我的整体评价 / Verdict
- 长程与体验结论(outcome_impact):
long_horizon与user_experience均判定为improved。前端未修改(visual_review结论为not_applicable:本 PR 仅涉 TS 控制面与后端/飞书出站投递逻辑,未改动任何渲染界面,且未遗漏范围unverified_scope:none)。 - 体量、兼容与语义结论:
code_volume为necessary,change_proportionality为proportionate;两个新增本地 JSON 结构为局部作用域配置与投递回执(semantic_alignment:not_applicable)。exact head5464acfc24e15eea3da7dc103f00b7c125c4512a满足本地准入要求,未依赖远程 CI。
英文简短结论
English verdict: APPROVE at head 5464acf. Scoped signal isolation, domain-neutral exact-head declaration filtering, steward_owner_report queuing, and idempotent chat_root delivery verified locally (16 TS, 173+112 Python, ruff, loopx check, canary premerge quick PASS) with default-off parity preserved.
交付摘要 / Summary
重构 Steward Signal Monitor 的作用域门控与直接汇报投递链路,支持多个独立配置的 GitHub PR Monitor 各自内部聚合、互不串扰唤醒,并在触发后直接向绑定的 Steward 会话(App 与 Feishu
chat_root)投递单篇可读汇报,替代逐 PR 创建散装user_action待办的轰炸模式。关键改动 / Key Changes
loopx/control_plane/collaboration/steward_managed_mode.ts,effect_runtime_handlers.ts):normalizeStewardSignalMonitorScope(steward_signal_monitor_scope_v0)与collaboration.steward.monitor.signal_scope.normalize,支持配置include_portfolio、include_inbox及领域中立的pr_filter(exclude_drafts、exclude_conflicting、effective_verdicts、required_approver_declarations、author_mode/authors、min_stalled_hours)。hasMatchingApprovedReviewerDeclaration按序重放exact_head_reviews并正确处理DISMISSED状态与多 reviewer 声明匹配。observeStewardSignalMonitor在未传入signal_scope时保持 100% legacy 行为与哈希不变;启用signal_scope时仅对作用域内信号计算result_hash,并在 PR 跨过min_stalled_hours阈值时仅于达标跃迁时翻转哈希(附带stalled_threshold_met: true而不随采集时钟抖动)。loopx/capabilities/native_chat/steward_monitor.py,loopx/chat_action_normalization.py,loopx/chat_actions.py,loopx/chat/monitor_actions.py):monitor.create与monitor.update校验并持久化steward-monitors/<goal_id>/scopes/<target_key>.json。StewardMonitor._collect_signal_monitor按需读取signal_scope,在关闭 portfolio/inbox 时跳过无关本地收集,并将过滤后的scoped_repository_items写入轻量快照供后续跟进消费。chat_rootReconciliation (loopx/capabilities/native_chat/steward_turn.py,loopx/extensions/lark/steward_reports.py,loopx/extensions/lark/private_conversations.py):StewardTurnHost新增可选steward_owner_report(<= 24000字符 Markdown 或{markdown},支持静默省略/null),在committed后原子落盘steward_monitor_report_delivery_v0回执队列并直接作为 App 端 Turn 回复,同时提示聚合汇报场景不再逐 PR 产出steward_user_actions。LarkStewardReports.pending()与_reconcile_monitor_reports()独立于每日周期汇报开关,校验原 Turn committed 状态与当前 binding/actor 授权,沿原始 P2P 受众以reply_placement="chat_root"、finalize_source=False发送一次并验证回执幂等去重。验证范围 / Verification
node --experimental-strip-types --test tests/control_plane_ts/steward_managed_mode.test.ts(16/16 passed).venv/bin/python -m pytest -n 4 -q tests/test_steward_generic_monitor_todo.py tests/test_lark_steward_reports.py tests/test_native_steward_turn_host.py tests/test_chat_operation_actions.py(173 passed).venv/bin/ruff checkon all changed Python files and tests.venv/bin/python examples/semantic-vocabulary-drift-smoke.py --git-diff origin/main.venv/bin/python -m loopx.entrypoint canary premerge --tier quick --from-git-diff --git-diff-base origin/main(passed)